Note that there are three shared libraries that make up the QuickDraw 3D
package and which should be installed in your Extensions folder:
QuickDraw™ 3D
QuickDraw™ 3D Manager
QuickDraw™ 3D Viewer
Your application only needs to link against QuickDraw3DLib.
New in this release is the 3D Viewer, which is similar to the QuickTime
movie controller, but it lets you manipulate 3D objects. You don’t need to
know any QD3D calls to make use of it and it only takes around 5 calls to add it to your application. If you want to use it, you only need to link against QD3DViewerLib (the header files is vcInterface.h).
As always, please “weak link” your apps and determine if they are
installed by checking that the entry point to the QD3D library has been
loaded, see page 98 of Develop 21.
Changes since Alpha
• QuickDraw 3D now does it memory allocation out Multifinder Temp
memory. This gives you total control over your heap and you can make
the size of your application’s heap as small as you need it to be for your
requirements. Note that in the case where we run out/can’t allocate out of
the temp memory, we will post an “out of memory” warning and start
allocating out of your application’s heap (we will continue posting the
warning every time we allocate out of your heap). When we run out of
memory, we will post an error, not a warning.
• We have further collapsed the headers from previous releases, all
geometries can now be found in QD3DGeometry.h.
Name changes - The enclosed MPW canon script will apply all the name
changes that are part of Beta.
Here is a description of the changes:
• All routines names were changed from Er to Q3.
• All types were changed from Et to TQ3, with the underscores in the
names removed.
• All constants were changed from Ec to kQ3, with the underscores in the
names removed.
• Functions that ended with _Draw, _Pick, were replaced by _Submit.
Whether you are doing drawing, picking, or bounding box operations is
determined by the Q3View_StartFoo call (Q3View_StartRendering,
Q3View_StartPicking, Q3View_StartBoundingBox, or
Q3View_StartBoundingSphere). This allows you to have only one traversal
loop defined as a function in your application, if you so desire.
ErBox_Pick
ErDisplayGroup_Pick
ErGeneralPolygon_Pick
ErGeometry_Pick
ErLine_Pick
ErMarker_Pick
ErNURBCurve_Pick
ErNURBPatch_Pick
ErPoint_Pick
ErPolygon_Pick
ErTriGrid_Pick
ErTriangle_Pick
• Attributes were collapsed into a single type and some attributes were
removed.
ErAttributeSet_Compact
ErAttributeSet_GetCSGEquation
ErAttributeSet_GetConstructiveSolidGeometryID
ErAttributeSet_GetType
ErAttribute_Delete
ErAttribute_Dispose
ErFaceAttributeSet_New
ErFaceAttributeSet_SizedNew
ErGeometryAttributeSet_New
ErGeometryAttributeSet_SizedNew
ErVertexAttributeSet_New
ErVertexAttributeSet_SizedNew
ErViewAttributeSet_New
ErViewAttributeSet_SizedNew
• Function names were cleaned up and made consistent:
Functions of type FooData_Empty are now Foo_EmptyData
ErBoxData_Empty
ErCStringData_Empty
ErGeneralPolygonData_Empty
ErHitData_Empty
ErLineData_Empty
ErMarkerData_Empty
ErNURBCurveData_Empty
ErNURBPatchData_Empty
ErPointData_Empty
ErPolygonData_Empty
ErTriGridData_Empty
ErTriangleData_Empty
ErUnknownBinaryData_Empty
ErUnknownTextData_Empty
The function to create a renderer based on a type has changed
ErRenderer_New Q3Renderer_NewFromType
The constant kQ3ViewStatus_Retraverse has been renamed kQ3ViewStatusRetraverse.
The clearimageState field from the drawContext structure has been removed.
This function allows the interactive renderer to selectively turn double buffering on/off depending on whether the rasterization engine clears the screen every frame. The net effect is slightly increased performance on some plug-in rasterizers at the expense of increased tearing.
The behavior of the memory storage object has changed. A distinction is now made as to the location of the memory being used (either in the application's space or internal to QD3D).
TQ3ObjectType Q3MemoryStorage_GetType(
TQ3StorageObject storage);
/*
* These calls COPY the buffer into QD3D space
*/
TQ3StorageObject Q3MemoryStorage_New(
const unsigned char *buffer,
unsigned long validSize);
TQ3Status Q3MemoryStorage_Set(
TQ3StorageObject storage,
const unsigned char *buffer,
unsigned long validSize);
/*
* These calls use the pointer given - you must dispose it when you're through
*/
TQ3StorageObject Q3MemoryStorage_NewBuffer(
unsigned char *buffer,
unsigned long validSize,
unsigned long bufferSize);
TQ3Status Q3MemoryStorage_SetBuffer(
TQ3StorageObject storage,
unsigned char *buffer,
unsigned long validSize,
unsigned long bufferSize);
Note that if the contents of the buffer are being used by QD3D, as in the case for textures maps images, you must call Q3MemoryStorage_SetBuffer when the contents of the buffer have been changed.
TQ3Status Q3MemoryStorage_GetBuffer(
TQ3StorageObject storage,
unsigned char **buffer,
unsigned long *validSize,
unsigned long *bufferSize);
CSG support for some hardware accelerators under the Interactive renderer has been added.
TQ3Status Q3InteractiveRenderer_SetCSGEquation(
TQ3RendererObject renderer,
TQ3CSGEquation equation);
This call allows you to set the CSG equation that will affect objects which have Attribute Sets with CSG IDs custom attributes.
TQ3Status Q3InteractiveRenderer_GetCSGEquation(
TQ3RendererObject renderer,
TQ3CSGEquation *equation);
TQ3Boolean Q3IsInitialized(void);
This function indicates whether QuickDraw 3D has already been initialized.
The routines Q3View_StartBoundingBox and Q3View_StartBoundingSphere take a TQ3ComputeBounds flag as the second parameter, which provides a hint as to the method used in the bounds calculation.
New types have been added:
typedef struct TQ3PolarPoint {
float r;
float theta;
} TQ3PolarPoint;
typedef struct TQ3SphericalPoint {
float rho;
float theta;
float phi;
} TQ3SphericalPoint;
And the following routines have been added in conjunction with them:
TQ3PolarPoint *Q3PolarPoint_Set(
TQ3PolarPoint *polarPoint,
float r,
float theta);
TQ3SphericalPoint *Q3SphericalPoint_Set(
TQ3SphericalPoint *sphericalPoint,
float rho,
float theta,
float phi);
The old "CartesianToPolar", "PolarToCartesian" ," CartesianToSpherical", and "SphericalToCartesian" routines in the Math library have been changed to:
Q3PolarPoint *Q3Point2D_ToPolar(
const TQ3Point2D *point2D,
TQ3PolarPoint *result);
TQ3Point2D *Q3PolarPoint_ToPoint2D(
const TQ3PolarPoint *polarPoint,
TQ3Point2D *result);
TQ3SphericalPoint *Q3Point3D_ToSpherical(
const TQ3Point3D *point3D,
TQ3SphericalPoint *result);
Q3Point3D *Q3SphericalPoint_ToPoint3D(
const TQ3SphericalPoint *sphericalPoint,
TQ3Point3D *result);
The clear color structure used in both the DrawContext and ViewHints is now of type TQ3ColorARGB, where the "a" component represents the alpha channel. The valid range for alpha is from 0.0 to 1.0, where 0.0 is transparent and 1.0 is solid.
• UV parameters
The parametric, UV, orientation is now as follows. The parametric origin is defined as the left bottom corner, with U increasing towards the right and Vs increasing towards the top. The origin of the texture images remains as top-left.
• The following calls have been removed:
ErController_Decomission
ErController_MoveTracker
ErDrawContext_ClearImageBuffer
ErDrawContext_GetActiveBuffer
ErDrawContext_GetClearImageState
ErDrawContext_SetActiveBuffer
ErDrawContext_SetClearImageState
ErDrawContext_UpdateFrontBuffer
ErElementClass_GetElementSize
ErFile_Open
ErGeneralPolygon_GetContourAttributeSet
ErGeneralPolygon_SetContourAttributeSet
ErLightGroup_FindLight
ErMatrix3x3_SetRotateAboutPoint_Deg
ErMatrix4x4_SetRotateAboutAxis_Deg
ErMatrix4x4_SetRotateAboutPoint_Deg
ErMatrix4x4_SetRotate_XYZ_Deg
ErMatrix4x4_SetRotate_X_Deg
ErMatrix4x4_SetRotate_Y_Deg
ErMatrix4x4_SetRotate_Z_Deg
ErMesh_PickHitGetInfo
ErOrderedDisplayGroup_CountObjectType
ErPick_GetFirstHit
ErPick_GetNextHit
ErPick_GetPreviousHit
ErPoint3D_To2D
ErQuaternion_SetRotateAboutAxis_Deg
ErQuaternion_SetRotateXYZ_Deg
ErQuaternion_SetRotateX_Deg
ErQuaternion_SetRotateY_Deg
ErQuaternion_SetRotateZ_Deg
ErRenderer_New
ErRenderer_SetIsBoundingBoxVisibleFunc
ErTracker_GetAbsolute
ErTracker_GetCoordinates
ErTracker_SetAbsolute
ErTracker_SetCoordinates
Q3DisplayGroup_BoundingBox
Q3DisplayGroup_BoundingSphere
Q3Geometry_BoundingBox
Q3Geometry_BoundingSphere
Q3View_StartBounds
Q3View_EndBounds
Q3File_BeginWrite
Q3File_EndWrite
all Q3Foo_Write functions
Writing is accomplished by using the _Submit calls. To begin writing the call Q3View_StartWriting has been added. To end writing, the call Q3View_EndWriting has been added.
Explanation:
ErController_Decomission
Renamed to ErController_Decommission.
ErController_MoveTracker
Replaced by the calls:
ErController_GetTrackerPosition
ErController_SetTrackerPosition
ErController_MoveTrackerPosition
ErController_GetTrackerOrientation
ErController_SetTrackerOrientation
ErController_MoveTrackerOrientation
ErDrawContext_ClearImageBuffer
This operation was tied too closely to certain types of renderers and
could not be supported by others or by certain HW accelerators. The
scene is cleared now as part of the Q3View_StartRendering call.
ErDrawContext_GetActiveBuffer
ErDrawContext_SetActiveBuffer
These calls dependent on certain features which can not be
supported by
certain types of accelerators/renderers. The double buffer state
variable
in the DrawContext controls the destination buffer.
ErDrawContext_GetClearImageState
ErDrawContext_SetClearImageState
These calls were redundant and their functionality is absorved by
the
ClearImageMethod in the DrawContext.
ErDrawContext_UpdateFrontBuffer
This operation was tied too closely to certain types of renderers and
could not be supported by others or by certain HW accelerators. The
front buffer is now updated as part of the Q3View_EndRendering
call. Please
read the description for Q3Renderer_Sync and Q3Renderer_Flush in
the
documentation.
ErFile_Open
This function has been split into two, Q3File_OpenRead and
Q3File_OpenWrite.
ErGeneralPolygon_GetContourAttributeSet
ErGeneralPolygon_SetContourAttributeSet
General polygons no longer have attribute sets per contour (didn't make
sense)
ErMatrix3x3_SetRotateAboutPoint_Deg
ErMatrix4x4_SetRotateAboutAxis_Deg
ErMatrix4x4_SetRotateAboutPoint_Deg
ErMatrix4x4_SetRotate_XYZ_Deg
ErMatrix4x4_SetRotate_X_Deg
ErMatrix4x4_SetRotate_Y_Deg
ErMatrix4x4_SetRotate_Z_Deg
You need to use the radians version of these functions.
ErMesh_PickHitGetInfo
Removed in favor of the new ShapePart object.
ErPick_GetFirstHit
Removed in favor of the original, and more useful, ErPick_GetHitData
ErPick_GetNextHit
Removed in favor of the original, and more useful, ErPick_GetHitData
ErPick_GetPreviousHit
Removed in favor of the original, and more useful, ErPick_GetHitData
ErPoint3D_To2D
Superseded by ErRationalPoint3D_To2D
ErQuaternion_SetRotateAboutAxis_Deg
ErQuaternion_SetRotateXYZ_Deg
ErQuaternion_SetRotateX_Deg
ErQuaternion_SetRotateY_Deg
ErQuaternion_SetRotateZ_Deg
You need to use the radians version of these functions.
ErRenderer_SetIsBoundingBoxVisibleFunc
<need explanation>
ErTracker_GetAbsolute
ErTracker_SetAbsolute
The notion of absolute trackers has been handled by usage of the
ErTracker_GetPosition and ErTracker_GetOrientation routines. These can
either return both the absolute and relative contributions to motion, or
return the absolute and relative combined contributions.
ErTracker_GetCoordinates
This call has been split into ErTracker_GetPosition and
ErTracker_GetOrientation.
ErTracker_SetCoordinates
This call has been split into ErTracker_SetPosition for absolute
contributions to position, ErTracker_MovePosition for relative position,
ErTracker_SetOrientation for absolute rotation and
ErTracker_MoveOrientation for relative orientation.
Q3DisplayGroup_BoundingBox
Q3DisplayGroup_BoundingSphere
Q3Geometry_BoundingBox
Q3Geometry_BoundingSphere
Q3View_StartBounds
Q3View_EndBounds
The same functionality is now achieved by using View_StartBoundingBox or ViewStartBoundingSphere. The resulting bounding volume is returned as part of the ViewEndBounds calls.
Q3File_BeginWrite
Q3File_EndWrite
all Q3Foo_Write functions
Writing is accomplished by using the _Submit calls. To begin writing the call Q3View_StartWriting has been added. To end writing, the call Q3View_EndWriting has been added.
HARDWARE ACCELERATION
Hardware acceleration happens "for free". All you need to do is use the
interactive renderer:
renderer = Q3Renderer_NewFromType
(kQ3RendererTypeInteractive);
And to make the images coherent, set up the drawContext to be double
buffered.
In addition, some hardware rasterizer engines (such as Apple's) can
actually make coherent images without double buffering. This can provide
a significant speed advantage, at the possible cost of some tearing. To take
advantage of such hardware, you keep the drawContext double buffered
(to say that you want the images coherent) and make the call
